6.3.3 Adding and Amending Styles

If none of the built-in styles is appropriate, you’ll probably want to create a new style definition, possibly based on an existing style. To do this, put the new style’s settings into a list with the following format; the list can then be passed as an argument to the function c-add-style. You can see an example of a style definition in Sample Init File.

Structure of a Style Definition List

([base-style] [(variable . value) …])

Optional base-style, if present, must be a string which is the name of the base style from which this style inherits. At most one base-style is allowed in a style definition. If base-style is not specified, the style inherits from the table of factory default values²⁰ instead. All styles eventually inherit from this internal table. Style loops generate errors. The list of pre-existing styles can be seen in Built-in Styles.

The dotted pairs (variable . value) each consist of a variable and the value it is to be set to when the style is later activated.²¹ The variable can be either a CC Mode style variable or an arbitrary Emacs variable. In the latter case, it is not made buffer-local by the CC Mode style system.

Two variables are treated specially in the dotted pair list:

c-offsets-alist

The value is in turn a list of dotted pairs of the form

(syntactic-symbol . offset)

as described in c-offsets-alist. These are passed to c-set-offset so there is no need to set every syntactic symbol in your style, only those that are different from the inherited style.

c-special-indent-hook

The value is added to c-special-indent-hook using add-hook, so any functions already on it are kept. If the value is a list, each element of the list is added with add-hook.

Styles are kept in the c-style-alist variable, but you should never modify this variable directly. Instead, CC Mode provides the function c-add-style for this purpose.

Function: c-add-style stylename description &optional set-p

Add or update a style called stylename, a string. description is the new style definition in the form described above. If stylename already exists in c-style-alist then it is replaced by description. (Note, this replacement is total. The old style is not merged into the new one.) Otherwise, a new style is added.

If the optional set-p is non-nil then the new style is applied to the current buffer as well. The use of this facility is deprecated and it might be removed from CC Mode in a future release. You should use c-set-style instead.

The sample .emacs file provides a concrete example of how a new style can be added and automatically set. See Sample Init File.

Variable: c-style-alist

This is the variable that holds the definitions for the styles. It should not be changed directly; use c-add-style instead.